/* 
 * DataBaseIntegration.java
 * 
 * Data de criação: 11/02/2010
 * 
 * O2SOLUTIONS - SOLUÇÕES EM TECNOLOGIA DA INFORMAÇÃO. 
 *
 */
package br.com.o2solutions.core.integration.repository;

import java.io.Serializable;
import java.util.List;
import java.util.Map;

import javax.persistence.NamedQuery;

/**
 * Interface para as operações básicas de acesso e manipulação de dados no
 * sistema.
 * 
 * @param <T>
 *            Tipo da Entidade que esta sendo manipulada
 * @author osvaldeir
 * @since 11/02/2010
 * 
 */

public interface DataBaseIntegration<T> {

	/**
	 * Realiza a inserção ou atualização de uma Entidade na base de dados
	 * 
	 * @param entity
	 *            Entidade a ser atualizada ou inserida
	 */

	public void saveOrUpdate(T entity);

	/**
	 * Realiza a inserção de uma Entidade na base de dados.
	 * 
	 * @param entity
	 *            Entidade a ser inserida.
	 */
	public void save(T entity);

	/**
	 * Realiza a atualizacao de uma Entidade na base de dados e, caso esta
	 * entidade não exista, e lancada uma {@link IntegrationException}
	 * 
	 * @param entity
	 *            Entidade a ser atualizada.
	 */
	public void update(T entity);

	/**
	 * Remove uma Entidade da base de dados. Neste caso o Id é obrigatório
	 * 
	 * @param entity
	 *            Entidade a ser removida
	 */

	public void remove(T entity);

	/**
	 * Retorna uma lista da Entidade que esta sendo pesquisada.
	 * 
	 * @return List<T> Lista de Entidades
	 */
	public List<T> findAll();

	/**
	 * Retorna uma lista de Entidade de acordo com a {@link NamedQuery} passada
	 * como parametro de execução. O nome da {@link NamedQuery} para pesquisa
	 * deve ser o nome da classe da entidade posfixada com o termo ".findAll".
	 * Ex: T.findAll ou Object.findAll.
	 * 
	 * @param namedQuery
	 *            NamedQuery a ser realizada para a pesquisa
	 * @param arguments
	 * @return
	 */
	public List<T> findByNamedQuery(String namedQuery, Object... arguments);

	/**
	 * Retorna uma lista da Entidade de acordo com a {@link NamedQuery}. Caso o
	 * parametro mappedArguments seja nulo ou vazio é lançada uma
	 * {@link IllegalArgumentException}.
	 * 
	 * @param namedQuery
	 *            NamedQuery a ser pesquisada
	 * @param mappedArguments
	 *            Mapa de argumentos para a realização da consulta.
	 * @return List<T> Uma coleção vazia ou preenchida com os objetos
	 *         resultantes da pesquisa.
	 */
	public List<T> findByMappedNamedQuery(String namedQuery,
			Map<String, Object> mappedArguments);

	/**
	 * Executa uma query de Atualização na Base (Modificação de Registros ou
	 * Remoção) a partir de uma {@link NamedQuery} informada. Caso a
	 * {@link NamedQuery} não exista é lançada uma {@link RuntimeException}
	 * 
	 * @param namedQuery
	 *            {@link NamedQuery} para execução
	 * @param arguments
	 *            Argumentos da {@link NamedQuery}
	 * @return Integer Número de registros afetados pela execução da
	 *         {@link NamedQuery}
	 */

	public Integer executeUpdate(String namedQuery, Object... arguments);

	/**
	 * Retorna a lista de Entidades cadastradas de acordo com o Objeto criterio
	 * de pesquisa
	 * 
	 * @param entity
	 * @return List<T>
	 */
	public List<T> findByCriterio(T entity);

	/**
	 * Retorna a Entidade pelo seu ID
	 * 
	 * @param id
	 *            Id da Entidade a ser pesquisada
	 * @return T Entidade
	 */
	public T findById(Serializable id);

	/**
	 * Descarrega os dados em Sessão para a base de dados.
	 */
	public void flush();

	/**
	 * Atualiza o estado da Entidade com a Base de Dados
	 * 
	 * @param entity
	 *            Entidada a ser atualizada
	 */
	public void refresh(T entity);

	Integer executeNativeUpdate(String namedQuery, Object... arguments);

}
